<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Guidelines for using poly_int (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Guidelines for using poly_int (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Guidelines for using poly_int (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="poly_005fint.html" rel="up" title="poly_int">
<link href="Miscellaneous-poly_005fint-routines.html" rel="prev" title="Miscellaneous poly_int routines">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
ul.mark-bullet {list-style-type: disc}
-->
</style>


</head>

<body lang="en">
<div class="section-level-extent" id="Guidelines-for-using-poly_005fint">
<div class="nav-panel">
<p>
Previous: <a href="Miscellaneous-poly_005fint-routines.html" accesskey="p" rel="prev">Miscellaneous <code class="code">poly_int</code> routines</a>, Up: <a href="poly_005fint.html" accesskey="u" rel="up">Sizes and offsets as runtime invariants</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Guidelines-for-using-poly_005fint-1"><span>10.9 Guidelines for using <code class="code">poly_int</code><a class="copiable-link" href="#Guidelines-for-using-poly_005fint-1"> &para;</a></span></h3>

<p>One of the main design goals of <code class="code">poly_int</code> was to make it easy
to write target-independent code that handles variable-sized registers
even when the current target has fixed-sized registers.  There are two
aspects to this:
</p>
<ul class="itemize mark-bullet">
<li>The set of <code class="code">poly_int</code> operations should be complete enough that
the question in most cases becomes &ldquo;Can we do this operation on these
particular <code class="code">poly_int</code> values?  If not, bail out&rdquo; rather than
&ldquo;Are these <code class="code">poly_int</code> values constant?  If so, do the operation,
otherwise bail out&rdquo;.

</li><li>If target-independent code compiles and runs correctly on a target
with one value of <code class="code">NUM_POLY_INT_COEFFS</code>, and if the code does not
use asserting functions like <code class="code">to_constant</code>, it is reasonable to
assume that the code also works on targets with other values of
<code class="code">NUM_POLY_INT_COEFFS</code>.  There is no need to check this during
everyday development.
</li></ul>

<p>So the general principle is: if target-independent code is dealing
with a <code class="code">poly_int</code> value, it is better to operate on it as a
<code class="code">poly_int</code> if at all possible, choosing conservatively-correct
behavior if a particular operation fails.  For example, the following
code handles an index <code class="code">pos</code> into a sequence of vectors that each
have <code class="code">nunits</code> elements:
</p>
<div class="example smallexample">
<pre class="example-preformatted">/* Calculate which vector contains the result, and which lane of
   that vector we need.  */
if (!can_div_trunc_p (pos, nunits, &amp;vec_entry, &amp;vec_index))
  {
    if (dump_enabled_p ())
      dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
                       &quot;Cannot determine which vector holds the&quot;
                       &quot; final result.\n&quot;);
    return false;
  }
</pre></div>

<p>However, there are some contexts in which operating on a
<code class="code">poly_int</code> is not possible or does not make sense.  One example
is when handling static initializers, since no current target supports
the concept of a variable-length static initializer.  In these
situations, a reasonable fallback is:
</p>
<div class="example smallexample">
<pre class="example-preformatted">if (<var class="var">poly_value</var>.is_constant (&amp;<var class="var">const_value</var>))
  {
    ...
    /* Operate on <var class="var">const_value</var>.  */
    ...
  }
else
  {
    ...
    /* Conservatively correct fallback.  */
    ...
  }
</pre></div>

<p><code class="code">poly_int</code> also provides some asserting functions like
<code class="code">to_constant</code>.  Please only use these functions if there is a
good theoretical reason to believe that the assertion cannot fire.
For example, if some work is divided into an analysis phase and an
implementation phase, the analysis phase might reject inputs that are
not <code class="code">is_constant</code>, in which case the implementation phase can
reasonably use <code class="code">to_constant</code> on the remaining inputs.  The assertions
should not be used to discover whether a condition ever occurs &ldquo;in the
field&rdquo;; in other words, they should not be used to restrict code to
constants at first, with the intention of only implementing a
<code class="code">poly_int</code> version if a user hits the assertion.
</p>
<p>If a particular asserting function like <code class="code">to_constant</code> is needed
more than once for the same reason, it is probably worth adding a
helper function or macro for that situation, so that the justification
only needs to be given once.  For example:
</p>
<div class="example smallexample">
<pre class="example-preformatted">/* Return the size of an element in a vector of size SIZE, given that
   the vector has NELTS elements.  The return value is in the same units
   as SIZE (either bits or bytes).

   to_constant () is safe in this situation because vector elements are
   always constant-sized scalars.  */
#define vector_element_size(SIZE, NELTS) \
  (exact_div (SIZE, NELTS).to_constant ())
</pre></div>

<p>Target-specific code in <samp class="file">config/<var class="var">cpu</var></samp> only needs to handle
non-constant <code class="code">poly_int</code>s if <code class="code">NUM_POLY_INT_COEFFS</code> is greater
than one.  For other targets, <code class="code">poly_int</code> degenerates to a compile-time
constant and is often interchangable with a normal scalar integer.
There are two main exceptions:
</p>
<ul class="itemize mark-bullet">
<li>Sometimes an explicit cast to an integer type might be needed, such as to
resolve ambiguities in a <code class="code">?:</code> expression, or when passing values
through <code class="code">...</code> to things like print functions.

</li><li>Target macros are included in target-independent code and so do not
have access to the implicit conversion to a scalar integer.
If this becomes a problem for a particular target macro, the
possible solutions, in order of preference, are:

<ul class="itemize mark-bullet">
<li>Convert the target macro to a target hook (for all targets).

</li><li>Put the target&rsquo;s implementation of the target macro in its
<samp class="file"><var class="var">cpu</var>.c</samp> file and call it from the target macro in the
<samp class="file"><var class="var">cpu</var>.h</samp> file.

</li><li>Add <code class="code">to_constant ()</code> calls where necessary.  The previous option
is preferable because it will help with any future conversion of the
macro to a hook.
</li></ul>
</li></ul>



</div>
<hr>
<div class="nav-panel">
<p>
Previous: <a href="Miscellaneous-poly_005fint-routines.html">Miscellaneous <code class="code">poly_int</code> routines</a>, Up: <a href="poly_005fint.html">Sizes and offsets as runtime invariants</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
